En este artículo se recopilan respuestas a las preguntas más frecuentes sobre el Remote API.

¿Existen limitaciones en el uso del API?

Las limitaciones globales están descritas en la documentación. Generalmente, alcanzar estas limitaciones indica que la aplicación desarrollada no está optimizada para trabajar con el API. Por ejemplo, realiza múltiples solicitudes de autorización en lugar de mantener una sesión activa.

También existen limitaciones en algunas solicitudes, mencionadas en la descripción de la solicitud en la documentación. Por ejemplo, solo se puede ejecutar un informe a la vez en una sesión. Si en la sesión hay resultados de un informe anterior, deben eliminarse con la solicitud report/cleanup_result antes de ejecutar el siguiente informe. Además, la solicitud para ejecutar informes no puede realizarse simultáneamente con algunas otras solicitudes.

¿Es posible organizar la transmisión de datos en tiempo real desde Wialon mediante el API?

No. Las solicitudes API funcionan bajo el principio de "solicitud-respuesta". Es decir, los datos en el lado receptor no se actualizarán sin enviar una solicitud.

Si es necesario recibir datos del equipo a medida que llegan nuevos mensajes, se pueden utilizar repetidores.

¿Cómo crear un localizador mediante el API?

Consideremos un ejemplo: es necesario crear un localizador con tiempo de vida ilimitado, que muestre unidades con ID del sistema 11111111 y 22222222, así como geocercas del recurso con ID del sistema 12345678, pero que no muestre los recorridos de las unidades.

Para ello, se debe usar la solicitud token/update:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/update&params=
{"callMode":"create","app":"locator","at":0,"dur":0,"fl":256,"p":"{\"note\":\"Bus\",\"zones\":1,\"tracks\":0}","items":[11111111,22222222,12345678]}&sid=SESSION_IDENTIFIER

En la respuesta a la solicitud estará presente el parámetro h, que contiene el valor del token. Para obtener el enlace deseado, es necesario insertar el valor del token en el enlace: 
https://hosting.wialon.com/locator/index.html?t=TOKEN_VALUE

¿Cómo obtener un token con acceso máximo y sin límite de tiempo de vida?

Si la creación del token se realiza a través del formulario extendido, se deben usar los parámetros access_type=-1 y duration=0. Por ejemplo:

https://hosting.wialon.com/login.html?client_id=APP_NAME&access_type=256&activation_time=0&duration=0&lang=en&flags=0&user=USER_NAME

Si la creación del token se realiza mediante la solicitud token/update, se deben usar los parámetros fl=-1 y dur=0. Por ejemplo:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/update&params=
{"callMode":"create","app":"Wialon Hosting","at":0,"dur":0,"fl":-1,"p":"{}"}&sid=SESSION_IDENTIFIER

¿Por qué al usar un token sin límite de tiempo puede devolver un error con el código 1?

El error con el código 1 indica que la sesión actual no es válida. El tiempo de vida del token no está directamente relacionado con la sesión.

Para solucionar la situación, es necesario realizar nuevamente la autorización. En la respuesta al inicio de sesión con el token, se incluirá el parámetro eid, cuyo valor es el identificador único de la sesión. Luego se utilizará en casi todas las solicitudes API.

¿Cómo corregir el error con el código 4?

El error con el código 4 corresponde a una entrada incorrecta, lo que puede significar:

• Tipo de datos incorrecto (numérico, texto, etc.);
• Nombres de parámetros incorrectos;
• Separadores incorrectos (comas, comillas, espacios, paréntesis, etc.);
• Falta de codificación para la transmisión en la URL.

Consideremos un ejemplo de solicitud con todos los errores mencionados:

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result&params={"format":"2";"compres":0;"outputFileName":"List of trips"}&sid=SESSION_IDENTIFIER

En este ejemplo se cometieron los siguientes errores:

• El parámetro format debe contener un número, pero como su valor está entre comillas, se interpreta como texto;
• En lugar del parámetro con el nombre compress se utilizó el parámetro con el nombre compres ;
• Para separar los parámetros se utilizó un punto y coma en lugar de una coma ;
• El carácter de espacio no fue codificado para la transmisión en la URL.

La solicitud correcta se verá de la siguiente manera:

https://hst-api.wialon.com/wialon/ajax.html?svc=report/export_result&params={"format":2,"compress":0,"outputFileName":"List%20of%20trips"}&sid=SESSION_IDENTIFIER

¿Por qué al usar IDs únicos de unidades se produce un error con el código 7?

En las solicitudes API no se utilizan los IDs únicos de las unidades de la pestaña Básicas, sino los IDs del sistema internos de los elementos. Por defecto, no se muestran en las interfaces web.

Para obtener los IDs del sistema de los elementos, se puede usar la solicitud de búsqueda de elementos por criterios (core/search_items). En la respuesta a esta solicitud, el parámetro id contendrá el valor buscado.

¿Por qué el acceso a un elemento está restringido, aunque el usuario tiene todos los derechos

Probablemente, el problema se debe a la falta de derechos en el token utilizado.

Para verificar los derechos del token, realice el inicio de sesión con él token:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login&params={"token":"TOKEN_VALUE"}

En la respuesta se incluirá el parámetro fl, que muestra los derechos actuales del token. Para cambiarlos, edite el token actual o cree uno nuevo.

¿Cómo obtener las últimas coordenadas de las unidades?

Para obtener las últimas coordenadas de varias unidades, se puede usar la solicitud de búsqueda de elementos por criterios (core/search_items). Es necesario especificar los flags de acceso, según los cuales en la respuesta se mostrarán los nombres de las unidades ("flag":1) y la información sobre la última ubicación de las unidades ("flag":1024). Los flags se pueden sumar entre sí, por lo que en la solicitud se usará el valor 1 + 1024 = 1025.

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*","sortType":"sys_name"},"force":1,"flags":1025,"from":0,"to":0}&sid=SESSION_IDENTIFIER

¿Cómo obtener una lista de todas las unidades disponibles para el usuario?

Para mostrar todas las unidades disponibles para el usuario, se puede usar la solicitud de búsqueda de elementos por criterios (core/search_items) con el valor "propValueMask":"*".

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

En la respuesta se devolverá una lista de unidades disponibles para el usuario cuyo identificador de sesión se utilizó en la solicitud.

¿Cómo obtener los nombres de los grupos a los que pertenece una unidad específica?

Para obtener los nombres de los grupos a los que pertenece una unidad con el ID del sistema 11112222, se debe usar la solicitud de búsqueda de elementos por criterios (core/search_items) con los valores "itemsType":"avl_unit_group", "propName":"sys_units" y "propType":"list".

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit_group","propName":"sys_units","propValueMask":11112222,"sortType":"sys_name","propType":"list"},"force":1,"flags":1,"from":0,"to":0}}&sid=SESSION_IDENTIFIER

¿Cómo obtener los nombres de las unidades de un grupo específico?

Para obtener los nombres de las unidades que pertenecen a un grupo con el nombre Group, se deben usar dos solicitudes de búsqueda de elementos por criterios (core/search_items): la primera buscará por el grupo de unidades (avl_unit_group) y la segunda por la unidad (avl_unit).

1. Primero, se debe obtener una lista de los IDs del sistema de las unidades que pertenecen al grupo (su nombre debe especificarse en el parámetro propValueMask):

   https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit_group","propName":"sys_name","propValueMask":"Group","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

    Respuesta

   {
   	"searchSpec":{
   		"itemsType":"avl_unit_group",
   		"propName":"sys_name",
   		"propValueMask":"Group",
   		"sortType":"sys_name",
   		"propType":"",
   		"or_logic":"0"
   	},
   	"dataFlags":1,
   	"totalItemsCount":1,
   	"indexFrom":0,
   	"indexTo":0,
   	"items":[
   		{
   			"nm":"Group",
   			"cls":5,
   			"id":10000000,
   			"mu":0,
   			"u":[
   				20000001,
   				20000002,
   				20000003
   			],
   			"uacl":-1
   		}
   	]
   }
   

2. En la respuesta a la solicitud anterior, se debe encontrar el parámetro u con los IDs del sistema de las unidades. Estos deben insertarse en el parámetro propValueMask para la siguiente solicitud de búsqueda:
   

   https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items&params={"spec":{"itemsType":"avl_unit","propName":"sys_id","propValueMask":"20000001,20000002,20000003","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

    Respuesta

   {
   	searchSpec:{
   		itemsType:"avl_unit",
   		propName:"sys_id",
   		propValueMask:"20000001,20000002,20000003",
   		sortType:"sys_name",
   		propType:"",
   		or_logic:"0"
   	},
   	dataFlags:1,
   	totalItemsCount:3,
   	indexFrom:0,
   	indexTo:0,
   	items:[
   		{
   			nm:"Unit_1",
   			cls:2,
   			id:20000001,
   			mu:0,
   			uacl:-1
   		},
   		{
   			nm:"Unit_2",
   			cls:2,
   			id:20000002,
   			mu:0,
   			uacl:-1
   		},
   		{
   			nm:"Unit_3",
   			cls:2,
   			id:20000003,
   			mu:0,
   			uacl:-1
   		}
   	]
   }
   

   Los nombres de las unidades se mostrarán en los parámetros nm.

¿Por qué difieren los resultados del informe en la interfaz y en la respuesta a la solicitud API?

Al ejecutar informes mediante solicitudes API, es importante no olvidar configurar la zona horaria para la sesión actual. Para ello, inmediatamente después de la autorización, se deben aplicar una vez las configuraciones de localización del usuario.

Ekaterina Grib,Customer Service Engineer 2023-09-01